7.04. Справочник по Azure Repos Git

ДЛЯ НОВИЧКОВНЕ ДЛЯ НОВИЧКОВНЕ ОБЯЗАТЕЛЬНОВ РАЗРАБОТКЕ

Разработчику Архитектору Инженеру

Справочник по Azure Repos Git

Azure Repos Git — это управляемая облачная система контроля версий на основе Git, входящая в состав Azure DevOps Services. Она предоставляет полную поддержку распределённого рабочего процесса Git с дополнительными возможностями управления, безопасности, интеграции и аналитики.

Основные элементы Azure Repos Git

Репозиторий (Repository)

Репозиторий — центральная единица хранения кода и истории изменений. Каждый репозиторий содержит:

Все коммиты
Ветки
Теги
Файлы и папки проекта
.git-метаданные (внутренне)

В Azure Repos один проект может содержать множество репозиториев. Репозитории создаются в рамках организации Azure DevOps.

Проект (Project)

Проект — контейнер для репозиториев, рабочих элементов, конвейеров, тестов и других артефактов. Проект определяет:

Область видимости доступа
Правила безопасности по умолчанию
Интеграцию с другими службами Azure DevOps

Организация (Organization)

Организация — корневой уровень в Azure DevOps. Она объединяет:

Проекты
Участников
Лицензии
Настройки безопасности на уровне организации
Политики по умолчанию

Ветвление и управление ветками

Главная ветка (Main / Master)

По умолчанию при создании репозитория создаётся ветка main (или master, в зависимости от настроек). Эта ветка считается стабильной и защищённой.

Feature-ветки

Используются для разработки новых функций. Имена часто начинаются с префикса feature/.

Release-ветки

Создаются для подготовки релизов. Префикс — release/.

Hotfix-ветки

Применяются для срочных исправлений в production. Префикс — hotfix/.

Защищённые ветки (Protected Branches)

Azure Repos позволяет настраивать политики защиты для веток. Защита применяется через Branch Policies.

Политики веток (Branch Policies)

Политики веток — правила, которые применяются к конкретным веткам или шаблонам имён веток. Политики можно настроить в интерфейсе Azure DevOps или через REST API.

Обязательные политики

Require a minimum number of reviewers
Минимальное количество ревьюеров, которые должны одобрить pull request.
Значения: от 1 до 10.
Дополнительно: можно требовать, чтобы каждый ревьюер явно нажал «Approve».
Check for linked work items
Требует привязки хотя бы одного рабочего элемента (work item) к pull request.
Значения: включено / выключено.
Check for comment resolution
Требует разрешения всех комментариев в pull request перед слиянием.
Значения: включено / выключено.
Build validation
Требует успешного прохождения указанного конвейера CI перед слиянием.
Параметры:
- Pipeline: имя или ID пайплайна
- Trigger: автоматический запуск или ручной
- Policy status: required / optional
- Display name: отображаемое имя проверки
Status checks
Требует наличия внешних статусов (например, от сторонних систем) со значением succeeded.
Параметры:
- Status name
- Author
- Expiration
File path restrictions
Запрещает изменения в указанных путях без специального разрешения.
Пример: *.prod.config — только члены группы «Release Managers» могут изменять.
Automatically include reviewers
Автоматически добавляет ревьюеров на основе пути к файлу или шаблона имени.
Пример: все изменения в /src/api/ → автоматически добавляется команда Backend.
Merge strategies
Определяет допустимые стратегии слияния:
- Basic merge
- Squash merge
- Rebase and fast-forward
- Semi-linear merge (rebase + merge commit)
Можно разрешить одну или несколько стратегий.

Pull Request (PR)

Pull Request — механизм предложения изменений из одной ветки в другую с последующим ревью, обсуждением и валидацией.

Состояния PR

Active — открыт, ожидает ревью
Completed — успешно слит
Abandoned — отменён

Возможности PR

Комментирование строк кода
Обсуждение на уровне файла или всего PR
Автоматическое назначение ревьюеров
Шаблоны описания PR
Автоматическое закрытие связанных work items при слиянии (через ключевые слова: Closes #123)
Draft PR — черновик, не готов к ревью

Шаблоны PR

Шаблоны создаются в файле .azuredevops/pull_request_template.md или в корне репозитория как PULL_REQUEST_TEMPLATE.md. Поддерживаются несколько шаблонов с разными именами.

Разрешения и безопасность

Уровни доступа

Reader — просмотр кода, PR, веток
Contributor — push, создание PR, комментирование
Collaborator — то же, что Contributor, но с дополнительными правами в некоторых организациях
Administrator — полный контроль над репозиторием, включая настройку политик

Группы безопасности

Project Readers
Project Contributors
Build Administrators
Project Administrators

Можно создавать собственные группы и назначать им права на уровне репозитория или ветки.

Права на уровне ветки

Для каждой ветки или шаблона ветки можно задать:

Force push
Delete branch
Contribute
Contribute to pull requests
Create branch
Bypass policies
Manage permissions

Настройки репозитория

Общие настройки

Default branch — ветка по умолчанию для клонирования и PR
Repository URL — HTTPS и SSH ссылки
Clone in VS Code / Visual Studio — кнопки быстрого клонирования
Initialize with README — опция при создании репозитория

Параметры обслуживания

Garbage collection — автоматическая очистка неиспользуемых объектов
Loose object compression — сжатие объектов Git
Prune unreachable objects — удаление недостижимых коммитов

Включение функций

Forks — разрешить создание форков (внутри проекта или публично)
Public access — сделать репозиторий публичным (только в публичных проектах)
Wiki — включить отдельный Wiki-репозиторий
Issues — использовать встроенные задачи (не путать с Azure Boards)

Интеграции

Azure Pipelines

Полная интеграция с CI/CD:

Автоматический запуск пайплайнов по push или PR
Отображение статуса сборки в PR
Блокировка слияния при провале сборки

Azure Boards

Автоматическая связь коммитов и PR с work items через #ID
Отображение связанных задач в интерфейсе PR
Автоматическое обновление состояния work item

REST API

Azure DevOps предоставляет полный REST API для управления репозиториями:

Создание/удаление репозиториев
Управление ветками
Создание PR
Получение истории коммитов
Загрузка файлов

Базовый URL: https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repoId}

Webhooks

Поддержка исходящих webhook-уведомлений на события:

git.push
git.pullrequest.created
git.pullrequest.merged
git.ref.updated

Целевой URL, секрет, фильтрация по событиям — настраиваются вручную.

CLI и инструменты

Azure CLI

Команды для работы с репозиториями:

az repos create --name MyRepo --project MyProject
az repos pr create --repository MyRepo --source-branch feature/x --target-branch main
az repos policy list --repository-id {id}

Требуется установка расширения: az extension add --name azure-devops

Git CLI

Стандартные команды Git работают без изменений:

git clone https://dev.azure.com/org/project/_git/repo
git checkout -b feature/new
git add .
git commit -m "Add new feature"
git push --set-upstream origin feature/new

Для аутентификации используется:

Personal Access Token (PAT)
Azure AD credentials (через credential manager)
SSH keys

Visual Studio / VS Code

Встроенные инструменты:

Создание PR из IDE
Просмотр изменений
Синхронизация веток
Интеграция с Azure Boards

Аналитика и отчётность

Insights (вкладка Analytics)

Commit trends — активность по дням/неделям
Code churn — объём изменений по файлам
Author contributions — вклад каждого участника
PR cycle time — время от создания PR до слияния
PR review depth — количество комментариев, ревьюеров

Экспорт данных

Через OData или REST API можно экспортировать:

Список всех коммитов
Историю PR
Статусы сборок
Связи с work items

Продвинутые функции

Git Hooks (серверные)

Azure Repos не поддерживает пользовательские серверные Git hooks. Вместо этого используются:

Branch policies
Pipeline triggers
Webhooks

Submodules и Subtrees

Полностью поддерживаются стандартные механизмы Git:

git submodule add
git subtree add

Но требуют ручного управления зависимостями.

Large File Storage (LFS)

Поддержка Git LFS:

Включается в настройках репозитория
Требует установки Git LFS локально
Хранение больших бинарных файлов вне основной истории

Файлы отслеживаются через .gitattributes:

*.psd filter=lfs diff=lfs merge=lfs -text

Sparse Checkout

Поддерживается через стандартный Git. Полезен для крупных монорепозиториев.

Partial Clone / Shallow Clone

Работает как в любом Git-хостинге:

git clone --depth 1 https://...

Ограничения и квоты

Максимальный размер репозитория: 250 ГБ (рекомендуется < 10 ГБ)
Максимальный размер файла: 5 ГБ (с LFS), 100 МБ без LFS
Количество репозиториев в проекте: не ограничено
Количество веток: не ограничено
Количество PR одновременно: не ограничено
Хранение LFS: включено по умолчанию, объём зависит от лицензии

Резервное копирование и восстановление

Azure Repos не предоставляет встроенных средств резервного копирования. Рекомендации:

Использовать локальные зеркала (git clone --mirror)
Настроить регулярный push в сторонний Git-сервер
Экспортировать через REST API

Восстановление после ошибок:

git reflog — для локального восстановления
Защита веток — предотвращает потерю истории
Администраторы могут восстановить удалённые ветки через UI (в течение 30 дней)

REST API: ключевые эндпоинты и параметры

Azure DevOps предоставляет полноценный REST API для управления репозиториями, ветками, коммитами и pull request’ами. Все запросы требуют аутентификации через Personal Access Token (PAT) или OAuth.

Базовый URL

https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}

Основные ресурсы

Репозитории

GET /repositories — список всех репозиториев в проекте
Параметры: includeLinks, includeAllUrls
POST /repositories — создание нового репозитория
Тело: { "name": "MyRepo", "project": { "id": "..." } }
DELETE /repositories/{id} — удаление репозитория

Ветки

GET /refs?filter=heads/ — список всех веток
Фильтр: filter=heads/release/ — только release-ветки
POST /refs — создание или обновление ветки
Тело: массив объектов с name, oldObjectId, newObjectId
DELETE /refs?filter=heads/feature/x — удаление ветки

Коммиты

GET /commits — история коммитов
Параметры: searchCriteria.itemPath, searchCriteria.fromCommitId, searchCriteria.toCommitId, top, skip
GET /commits/{commitId} — детали конкретного коммита
POST /commits — создание коммита напрямую через API (редко используется)

Pull Requests

GET /pullrequests — список PR
Параметры: status (active, completed, abandoned), creatorId, reviewerId, sourceRefName, targetRefName

POST /pullrequests — создание PR
Тело:

{
  "sourceRefName": "refs/heads/feature/login",
  "targetRefName": "refs/heads/main",
  "title": "Add login form",
  "description": "Implements basic auth UI",
  "reviewers": [
    { "id": "user-guid" }
  ]
}

PATCH /pullrequests/{id} — обновление PR (например, статуса)
POST /pullrequests/{id}/threads — добавление комментария к PR

Политики

GET /policies/configurations — список политик для репозитория

POST /policies/configurations — создание политики
Пример политики «минимум 2 ревьюера»:

{
  "type": { "id": "fa4e907d-c16b-4a4c-9df2-095f3e1c938b" },
  "settings": {
    "minimumApproverCount": 2,
    "creatorVoteCounts": false,
    "allowDownvotes": false
  }
}

Интеграция с Azure Pipelines: триггеры на Pull Request

В YAML-пайплайнах можно настроить автоматический запуск при открытии или обновлении PR.

Пример конфигурации

trigger: none  # отключаем обычный push-триггер

pr:
  branches:
    include:
      - main
      - release/*
  paths:
    include:
      - src/
    exclude:
      - docs/

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo "Running PR validation"
- task: DotNetCoreCLI@2
  inputs:
    command: 'test'
    projects: '**/*Tests/*.csproj'

Параметры секции `pr`

branches.include — ветки, в которые слияние запускает пайплайн
branches.exclude — исключения
paths.include/exclude — фильтрация по изменённым файлам
Можно использовать autoCancel — отмена предыдущих запусков при новых коммитах

Статус в PR

После выполнения пайплайн отправляет статус:

succeeded — зелёная галочка
failed — красный крест
pending — ожидание

Этот статус учитывается в политике Build validation.

Аутентификация и доступ

Personal Access Token (PAT)

Создаётся в User Settings → Personal Access Tokens
Область: Code (read and write)
Используется как пароль при HTTPS-клонировании:
```
git clone https://<username>:<PAT>@dev.azure.com/org/project/_git/repo
```

SSH-ключи

Генерируются локально: ssh-keygen -t rsa -b 4096
Публичный ключ добавляется в User Settings → SSH Public Keys

Клонирование:

git clone git@ssh.dev.azure.com:v3/org/project/repo

Azure AD

Для корпоративных аккаунтов поддерживается SSO через Azure Active Directory
Требует настройки в организации DevOps

Git Credential Manager

Автоматически сохраняет PAT или использует интерактивный вход
Поддерживается в Windows, macOS, Linux

Миграция в Azure Repos

Из GitHub / GitLab / Bitbucket

Клонировать исходный репозиторий с --mirror:
```
git clone --mirror https://github.com/user/repo.git
```

Добавить remote Azure Repos:

cd repo.git
git remote set-url --push origin https://dev.azure.com/org/project/_git/repo

Запушить всё:
```
git push --mirror
```

Перенос истории, тегов, веток

--mirror переносит всё: коммиты, ветки, теги, заметки
LFS-объекты требуют отдельной миграции через git lfs fetch --all && git lfs push --all

Сохранение авторов

Имена и email из коммитов сохраняются без изменений
Если email не совпадает с Azure AD, автор отображается как «Unknown»

Сравнение с другими платформами

Функция	Azure Repos	GitHub	GitLab
Защита веток	Branch Policies	Branch Protection Rules	Protected Branches
PR ↔ Work Items	Встроенная интеграция	Projects + Issues	Issues + Epics
CI/CD	Azure Pipelines	GitHub Actions	GitLab CI
LFS	Включено по умолчанию	Требует включения	Включено
Fork внутри проекта	Да	Только в рамках аккаунта/организации	Да
REST API	Полный, версионированный	GraphQL + REST	REST + GraphQL
Webhooks	Да	Да	Да
Code Owners	Через политики	CODEOWNERS файл	CODEOWNERS файл
Draft PR	Да	Да	WIP Merge Requests

Azure Repos особенно силён в глубокой интеграции с Azure DevOps: рабочие элементы, пайплайны, тесты, артефакты — всё в единой системе.

Практические рекомендации

Именование веток

Используйте префиксы: feature/, hotfix/, release/
Избегайте пробелов и специальных символов
Добавляйте Jira/GitHub ID, если используется внешняя система: feature/PROJ-123-login

Шаблоны PR

Создайте .azuredevops/pull_request_template.md:

## Описание
Краткое описание изменений.

## Связанные задачи
- closes #123
- relates to #456

## Проверки
- [ ] Пройдены unit-тесты
- [ ] Обновлена документация
- [ ] Проверено вручную

Автоматическое удаление веток

В настройках репозитория включите:

Automatically delete source branch after merge

Это снижает количество "мёртвых" веток.

Использование squash merge

Для feature-веток рекомендуется Squash merge — один чистый коммит в main.

Для долгоживущих веток (например, develop) — Basic merge для сохранения истории.

Работа с большими репозиториями

Крупные репозитории (монорепозитории, legacy-код, мультимедийные проекты) требуют особых подходов к управлению производительностью и хранению.

Ограничения

Максимальный размер репозитория: 250 ГБ
Максимальный размер файла без LFS: 100 МБ
Рекомендуемый рабочий размер: < 10 ГБ

Оптимизация клонирования

Использование shallow clone:

git clone --depth 1 https://dev.azure.com/org/project/_git/repo

Sparse checkout — выборочное извлечение файлов:

git clone --filter=blob:none --sparse https://...
git sparse-checkout set src/backend

Partial clone — загрузка только нужных объектов:
```
git clone --filter=tree:0 https://...
```

Управление историей

BFG Repo-Cleaner или git filter-repo — для удаления больших файлов из истории
После очистки — принудительный push с флагом --force-with-lease
Включение garbage collection в настройках репозитория

Разделение монорепозитория

Создание отдельных репозиториев по микросервисам
Использование submodules или subtrees для зависимостей
Поддержка общих библиотек через Azure Artifacts или private npm/PyPI

Git LFS (Large File Storage)

Git LFS заменяет большие файлы указателями, храня их отдельно.

Настройка

Установка LFS:
```
git lfs install
```

Отслеживание файлов:

git lfs track "*.psd"
git lfs track "assets/**/*.mp4"

Файл .gitattributes автоматически обновляется:

*.psd filter=lfs diff=lfs merge=lfs -text
assets/**/*.mp4 filter=lfs diff=lfs merge=lfs -text

Хранение и квоты

LFS включён по умолчанию в Azure Repos
Объём хранения зависит от лицензии:
- Free: 1 ГБ
- Basic: 10 ГБ
- Stakeholder: не поддерживается
Дополнительное хранилище можно приобрести отдельно

Перенос LFS из других систем

Экспорт:
```
git lfs fetch --all
```

Импорт в Azure Repos:

git remote set-url origin https://dev.azure.com/...
git lfs push --all origin

Ошибки и диагностика

This repository is over its data quota — превышена квота LFS
Smudge error — клиент не может скачать LFS-объект (часто из-за отсутствия аутентификации)
Решение: использовать PAT с правами Code (read) или настроить SSH

Политики на уровне организации

Политики могут применяться глобально ко всем проектам в организации.

Типы политик

Default branch name — задаёт имя ветки по умолчанию (main, trunk, и т.д.)
Forking policy — разрешить/запретить форки внутри организации
Repository creation policy — кто может создавать репозитории (только администраторы / все участники)
Public repository policy — разрешить публичные репозитории (только в публичных проектах)

Применение через REST API

PATCH https://dev.azure.com/{org}/_apis/policy/configurations?api-version=7.0

Тело запроса определяет тип политики и её параметры.

Наследование

Политики на уровне организации применяются ко всем новым репозиториям
В отдельных репозиториях можно переопределить настройки

Аудит действий и логирование

Azure DevOps предоставляет журналы аудита для отслеживания изменений.

Доступные события

Создание/удаление репозитория
Изменение политик веток
Push в защищённую ветку с обходом (bypass)
Удаление ветки
Изменение прав доступа

Просмотр журналов

Через UI: Organization Settings → Auditing

Через REST API:

GET https://auditservice.dev.azure.com/{org}/_apis/audit/auditlog

Фильтрация по типу события, пользователю, дате

Экспорт

CSV-выгрузка через UI
Интеграция с Azure Monitor и SIEM-системами через вебхуки

Webhook-события и payload

Webhooks отправляют JSON-уведомления на внешние URL при событиях в репозитории.

Поддерживаемые события

git.push
git.pullrequest.created
git.pullrequest.merged
git.pullrequest.abandoned
git.ref.updated
git.repository.created
git.repository.deleted

Пример payload: `git.push`

{
  "subscriptionId": "guid",
  "notificationId": 123,
  "id": "repo-id",
  "eventType": "git.push",
  "publisherId": "tfs",
  "message": {
    "text": "Push to main by John Doe"
  },
  "detailedMessage": {
    "text": "3 new commits pushed to main"
  },
  "resource": {
    "commits": [
      {
        "commitId": "a1b2c3d4",
        "author": { "name": "John Doe", "email": "john@contoso.com" },
        "comment": "Fix login bug"
      }
    ],
    "refUpdates": [
      {
        "name": "refs/heads/main",
        "oldObjectId": "old-sha",
        "newObjectId": "new-sha"
      }
    ],
    "repository": {
      "id": "repo-id",
      "name": "MyApp",
      "url": "https://dev.azure.com/org/project/_git/MyApp"
    }
  }
}

Безопасность webhooks

Поддержка HMAC-подписи (в заголовке X-VSS-Signature)
Возможность задать secret token для проверки источника
Автоматическая повторная отправка при ошибке (до 5 попыток)

Справочник по Azure Repos Git​

Основные элементы Azure Repos Git​

Репозиторий (Repository)​

Проект (Project)​

Организация (Organization)​

Ветвление и управление ветками​

Главная ветка (Main / Master)​

Feature-ветки​

Release-ветки​

Hotfix-ветки​

Защищённые ветки (Protected Branches)​

Политики веток (Branch Policies)​

Обязательные политики​

Pull Request (PR)​

Состояния PR​

Возможности PR​

Шаблоны PR​

Разрешения и безопасность​

Уровни доступа​

Группы безопасности​

Права на уровне ветки​

Настройки репозитория​

Общие настройки​

Параметры обслуживания​

Включение функций​

Интеграции​

Azure Pipelines​

Azure Boards​

REST API​

Webhooks​

CLI и инструменты​

Azure CLI​

Git CLI​

Visual Studio / VS Code​

Аналитика и отчётность​

Insights (вкладка Analytics)​

Экспорт данных​

Продвинутые функции​

Git Hooks (серверные)​

Submodules и Subtrees​

Large File Storage (LFS)​

Sparse Checkout​

Partial Clone / Shallow Clone​

Ограничения и квоты​

Резервное копирование и восстановление​

REST API: ключевые эндпоинты и параметры​

Базовый URL​

Основные ресурсы​

Репозитории​

Ветки​

Коммиты​

Pull Requests​

Политики​

Интеграция с Azure Pipelines: триггеры на Pull Request​

Пример конфигурации​

Параметры секции pr​

Статус в PR​

Аутентификация и доступ​

Personal Access Token (PAT)​

SSH-ключи​

Azure AD​

Git Credential Manager​

Миграция в Azure Repos​

Из GitHub / GitLab / Bitbucket​

Перенос истории, тегов, веток​

Сохранение авторов​

Сравнение с другими платформами​

Практические рекомендации​

Именование веток​

Шаблоны PR​

Автоматическое удаление веток​

Использование squash merge​

Работа с большими репозиториями​

Ограничения​

Оптимизация клонирования​

Управление историей​

Разделение монорепозитория​

Git LFS (Large File Storage)​

Настройка​

Хранение и квоты​

Справочник по Azure Repos Git

Основные элементы Azure Repos Git

Репозиторий (Repository)

Проект (Project)

Организация (Organization)

Ветвление и управление ветками

Главная ветка (Main / Master)

Feature-ветки

Release-ветки

Hotfix-ветки

Защищённые ветки (Protected Branches)

Политики веток (Branch Policies)

Обязательные политики

Pull Request (PR)

Состояния PR

Возможности PR

Шаблоны PR

Разрешения и безопасность

Уровни доступа

Группы безопасности

Права на уровне ветки

Настройки репозитория

Общие настройки

Параметры обслуживания

Включение функций

Интеграции

Azure Pipelines

Azure Boards

REST API

Webhooks

CLI и инструменты

Azure CLI

Git CLI

Visual Studio / VS Code

Аналитика и отчётность

Insights (вкладка Analytics)

Экспорт данных

Продвинутые функции

Git Hooks (серверные)

Submodules и Subtrees

Large File Storage (LFS)

Sparse Checkout

Partial Clone / Shallow Clone

Ограничения и квоты

Резервное копирование и восстановление

REST API: ключевые эндпоинты и параметры

Базовый URL

Основные ресурсы

Репозитории

Ветки

Коммиты

Pull Requests

Политики

Интеграция с Azure Pipelines: триггеры на Pull Request

Пример конфигурации

Параметры секции `pr`

Статус в PR

Аутентификация и доступ

Personal Access Token (PAT)

SSH-ключи

Azure AD

Git Credential Manager

Миграция в Azure Repos

Из GitHub / GitLab / Bitbucket

Перенос истории, тегов, веток

Сохранение авторов

Сравнение с другими платформами

Практические рекомендации

Именование веток

Шаблоны PR

Автоматическое удаление веток

Использование squash merge

Работа с большими репозиториями

Ограничения

Оптимизация клонирования

Управление историей

Разделение монорепозитория

Git LFS (Large File Storage)

Настройка

Хранение и квоты